C++

Reference

<ostream>

ostream

public member function
<ostream> <iostream>

std::operator<< (ostream)

single character (1)
ostream& operator<< (ostream& os, char c);ostream& operator<< (ostream& os, signed char c);ostream& operator<< (ostream& os, unsigned char c);
character sequence (2)
ostream& operator<< (ostream& os, const char* s);ostream& operator<< (ostream& os, const signed char* s);ostream& operator<< (ostream& os, const unsigned char* s);
single character (1)
ostream& operator<< (ostream& os, char c);ostream& operator<< (ostream& os, signed char c);ostream& operator<< (ostream& os, unsigned char c);
character sequence (2)
ostream& operator<< (ostream& os, const char* s);ostream& operator<< (ostream& os, const signed char* s);ostream& operator<< (ostream& os, const unsigned char* s);
rvalue insertion (3)
template<class charT, class traits, class T>basic_ostream<charT,traits>&  operator<< (basic_ostream<charT,traits>&& os, const T& val);
Insert characters
This operator (<<) applied to an output stream is known as insertion operator, and performs formatted output:

(1) single character
Inserts the character c into os.
(2) character sequence
Inserts the C-string s into os.
The terminating null character is not inserted into os.
The length of the c-string is determined beforehand (as if calling strlen).
(3) rvalue insertion
Allows inserting into rvalue ostream objects, with the same effect as inserting into lvalues: It effectively calls: os<<val.

The function inserts at least os.width() characters into os: if the characters to insert are less, they are padded with fill characters inserted before c or s, unless os's adjustfield setting is left (in this case, the fill characters are inserted after c or s).

Internally, the function accesses the output sequence by first constructing a sentry object. Then (if good), it inserts the characters described above into its associated stream buffer object as if calling its member function sputc. It then resets the field width to zero, and finally destroys the sentry object before returning.

Parameters

os
Output stream object where characters are inserted.
c
Character to insert.
s
Pointer to a null-terminated sequence of characters (a c-string).
val
ValueObject inserted.
T shall be a type supported as right-hand side argument either by this function or by os's member function operator<<.
charT and traits are the class template parameters of ostream (see basic_ostream).

Return Value

The ostream object (os).

Errors are signaled by modifying the internal state flags:
flagerror
eofbit-
failbitThe function failed while formatting the output (it may also be set if the construction of sentry failed).
badbitEither the insertion on the stream failed, or some other error happened (such as when this function catches an exception thrown by an internal operation).
When set, the integrity of the stream may have been affected.
Multiple flags may be set by a single operation.

If the operation sets an internal state flag on os that was registered with its member exceptions, the function throws an exception of its member type failure.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
// example on insertion
#include <iostream>     // std::cout

int main () {

  const char str[] = "Example string";
  char ch = 'X';

  std::cout << str << '\n';     // Insert string

  std::cout.width(5);
  std::cout.fill('*');

  std::cout << ch << '\n';      // Insert single character

  return 0;
}

Output:
Example string
****X


Data races

Accesses s (2). Modifies os.
Concurrent access to the same stream object may cause data races, except for the standard stream objects (cout, cerr, clog) when these are synchronized with stdio (in this case, no data races are initiated, although no guarantees are given on the order in which characters from multiple threads are inserted).

Exception safety

Basic guarantee: if an exception is thrown, all objects involved are in valid states.
It throws an exception of member type failure if the resulting error state flag for is is not goodbit and member exceptions was set to throw for that state in is.
Any exception thrown by an internal operation is caught and handled by the function, setting is's badbit flag. If badbit was set on the last call to exceptions for is, the function rethrows the caught exception.

If s does not point to a null terminated character sequence, it causes undefined behavior.

See also

ostream::operator<<
Insert formatted output (public member function)
ostream::put
Put character (public member function)
operator>> (istream)
Extract characters (public member function)